home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / qwik30.arc / QWIK30.DOC < prev    next >
Encoding:
Text File  |  1987-08-31  |  17.8 KB  |  381 lines
  1.                                                            August 31, 1987
  2.  
  3.                               QWIK SCREEN PROCEDURES
  4.                                    Version 3.0
  5.  
  6.         PURPOSE:
  7.  
  8.         QWIK screen procedures permit fast screen writing on IBM 
  9.         compatibles on any IBM adapter including the new PS/2 systems 
  10.         without "snow" or flicker effects and is compatible with ANY 
  11.         column format (e.g. 40/80 or variable).  Written in Turbo Pascal 
  12.         inline assembler, these procedures are lightning fast.  The code 
  13.         has also been condensed as much as possible without sacrificing 
  14.         speed - only 1.5k bytes of compiled code for all 18 procedures!
  15.  
  16.  
  17.         TEST DRIVE:
  18.  
  19.         Compile and run QWIKDEMO.PAS to get a feel for features and speed.
  20.  
  21.  
  22.         IMPROVEMENTS:
  23.  
  24.         In this version, I have updated the initialization procedure to 
  25.         accommodate the new IBM PS/2 family of computers as well as the 
  26.         PCjr and the PC convertible.  Two new cursor procedures were 
  27.         added.  The module addressing was improved.
  28.  
  29.         After much thought, I have decided to make these procedures into 
  30.         ShareWare.  The cost may range from $5 to $15 depending on your 
  31.         application.  I do enjoy assisting others in their programming, 
  32.         but lack of reimbursement is expensive for me!  Please help out.  
  33.         See the license statement in LICENSE.ARC for details.  If the 
  34.         response will let me break even, I will continue support.
  35.  
  36.  
  37.         PROCEDURES:
  38.  
  39.         In this version, QWIK30.ARC contains:
  40.  
  41.           Qinit   .inc:  Initializing procedure required to be executed
  42.                          first and just once before any Q procedures.
  43.           Qinit   .doc:  Document for Qinit.inc.
  44.           Qwrites .inc:  Five Quick direct screen writing procedures:
  45.                          QwriteLV - referenced (VAR) strings, specified
  46.                                     length and index.
  47.                          QwriteV  - referenced (VAR) strings
  48.                          Qwrite   - value strings
  49.                          QwriteC  - value strings, self-centering
  50.                          QwriteCV - referenced (VAR) strings, self-
  51.                                     centering
  52.           Qfills  .inc:  Four Quick direct screen filling procedures
  53.                          in Rows-by-Cols block parameters:
  54.                          QfillC   - repetitive filling with the same
  55.                                     character and self-centering
  56.                          Qfill    - repetitive filling with the same
  57.                                     character
  58.                          Qattr    - repetitive filling with the same
  59.                                     attribute only
  60.                          QattrC   - repetitive filling with the same
  61.                                     attribute and self-centering
  62.           Qstores .inc:  Two Quick storing procedures:
  63.                          QstoreToMem - Saves a Rows-by-Cols block
  64.                                        to memory.
  65.                          QstoreToScr - Restores a Rows-by-Cols block
  66.                                        to any screen page.
  67.           Qpage   .inc:  Two Quick direct screen changing procedures:
  68.                          QviewPage  - Changes the page to be
  69.                                       displayed - up to 8!
  70.                          QwritePage - Sets the page on which the
  71.                                       Q procedures are writing.  You
  72.                                       don't have to write just on
  73.                                       the displayed page!
  74.           Cursor  .inc:  Four Quick cursor procedures:
  75.                          GotoRC       - inverse of Turbo's GotoXY
  76.                          ChangeCursor - changes shape and visibility
  77.                                         of the cursor; saves old, too!
  78.                          CursorOff    - Hides cursor.
  79.                          CursorOn     - Reveals cursor, again.
  80.           Cursor  .doc:  Document for Cursor.inc.
  81.           Qwik30  .inc:  Has all of the above routines but compiles much
  82.                          faster because there are few comments.
  83.           Qwik30  .doc:  This document.
  84.           QwikDemo.pas:  A demonstration program showing the features and
  85.                          speed of all procedures and is written primarily
  86.                          for color cards, but also works on MDA.  
  87.           Qbench  .pas:  A timing program that shows "screens/second" for
  88.                          the Q procedures.
  89.           Qinitest.pas:  A program that verifies the equipment detected
  90.                          by Qinit.inc.
  91.           TimerD12.inc:  Include file to measure elapsed time.
  92.           License .arc:  ARC file containing license agreements
  93.  
  94.  
  95.         PROGRAMMING:
  96.  
  97.         To use the procedures, just simply pick out the ones you need and
  98.         include them in your programs.  QINIT.INC must be included first.
  99.         Only one initializing statement is necessary before Q procedures
  100.         are used (not required for cursor.inc):
  101.  
  102.             Qinit;
  103.  
  104.         This procedure automatically configures the procedures to your
  105.         machine and also makes it portable to others.  Procedures in 
  106.         QWRITES.INC and QFILLS.INC work with or without attributes 
  107.         changes. 
  108.  
  109.         All of the procedures work with TurboPower's Optimizer programs 
  110.         without modification.  With TLC, you can use the -C option.
  111.  
  112.  
  113.         MODULES:
  114.  
  115.         The coding has been reduced by making the display loops into a
  116.         subroutine and programming the procedures to access it.  These
  117.         were combined to make modules - two in this package.  The 
  118.         procedures can be placed in the usual order of Pascal protocol.
  119.         The program was written specifically for Turbo 3.0.
  120.  
  121.  
  122.         PARAMETERS:
  123.  
  124.         Row/Col - The procedures do not check for bounds on the screen,
  125.         so be sure to stay in range.  The procedures were designed for
  126.         the upper left column on the screen to be 1,1.  If you want 0,0,
  127.         refer to MODIFICATIONS below.  They also wrap to the next line;
  128.         they do not truncate at EOL.  You of course can have something
  129.         like Row:=1 and Col:=255 which is equivalent to Row:=3 and
  130.         Col:=15 on a screen with 80 columns.
  131.  
  132.         ColL/ColR - In QwriteC, QwriteCV, QfillC, and QattrC, the left
  133.         and right columns are simply averaged.  To center on the full
  134.         width of an 80 column display, set ColL:=1 and ColR:=80.  To
  135.         center on a certain column number, set both values equal to that
  136.         column number.
  137.  
  138.         Rows/Cols - They can be any positive integer to define the block
  139.         - Rows-by-Columns starting at Row, Col.  Values <=0 will simply
  140.         abort the procedure.  Please keep Cols limited to one row.
  141.  
  142.         Attr - The attributes range from 0 to 255.  Values greater than
  143.         255 will be operated by modulo 256 to stay useful.  Negative
  144.         values suppress any changes to the screen attributes and use
  145.         what's currently on the screen.  For help with attribute values,
  146.         use Brian Foley's FWATTR.INC on Borland's Programming Forum on
  147.         CompuServe in Turbo Pascal Data Library for MSDOS.  You can also
  148.         use Turbo's TextColor and TextBackground procedures, and then
  149.         use an absolute variable assigned at Dseg:8 (see QWIKDEMO.PAS for
  150.         an example).
  151.  
  152.         Length - In QwriteLV, you can write partial strings by specifying 
  153.         the Length and starting index (St[i]).  All other Qwrite 
  154.         procedures assume length is the value at St[0] and the starting 
  155.         index is St[1]. Length can be any positive integer.
  156.  
  157.         St - The original type was set for string length of 80 characters
  158.         which my be changed to any value between 1 and 255.  Be sure to
  159.         change all type statements to reflect it though!
  160.  
  161.         Source/Dest - For Qstores.inc, this can be a pointer for the heap
  162.         or an array variable.  Be sure there is sufficient room.  Storage
  163.         requirements are: (Rows * Cols shl 1) which is two bytes for
  164.         every column.  For pointers use a format such as:
  165.  
  166.             Var  MemPtr: ^byte;
  167.             GetMem (MemPtr,Rows*Cols shl 1);
  168.             QstoreToMem (Row,Col,Rows,Cols,MemPtr^);
  169.  
  170.         Page - The page range depends upon your adapter.  See QINIT.DOC 
  171.         for the possible ranges.
  172.  
  173.         Order - You may rearrange the parameters in any order you prefer.
  174.         The arrangement was made to facilitate readability and keeping
  175.         the coordinates on the left side of the display.
  176.  
  177.  
  178.         PAGING:
  179.  
  180.         If you have a CGA or better, you already have memory on your card 
  181.         for more than the 80x25 display you normally see.  The two page 
  182.         procedures allow you to use Q screen procedures on these other 
  183.         pages and display which ever you choose.  However, Turbo's 
  184.         procedures such as Write, Window, and GotoXY are dedicated to page 
  185.         0 only. I have included GotoRC as one procedure that works on all 
  186.         pages.  If you want more procedures for this, refer to Neil 
  187.         Rubenking's VIDPAG.PAS on Borland's Programming Forum.  Be sure to 
  188.         end your programs with "QviewPage (0);".
  189.  
  190.  
  191.         SPEED:
  192.  
  193.         How fast is fast?  Well, I thought it would be good idea to have
  194.         some criteria to get a feeling for speed.  The units I decided
  195.         to use for comparison are "screens/second".  To make one screen,
  196.         a procedure is repeated with a FOR loop to fill several 80x25
  197.         pages and timed.  QwriteXX use 80 character strings, and Qattr
  198.         and Qfill use Rows:=25 and Cols:=80.  Here are some samples from 
  199.         the systems that have been tested.  My own computer is the 
  200.         AT&T 6300+ which uses Intel 80286.  Monochrome (MDA) speeds are 
  201.         identical to EGA speeds.
  202.  
  203.         ------------------ S C R E E N S / S E C O N D ------------------
  204.                    Chng  XT(4.77 MHz)  M50    M30    PCC      ATT 6300+
  205.         Procedure  Attr  EGA     CGA   MCGA   VGA    LCD     EGA     CGA     
  206.         ---------  ----  ------------  -----  -----  -----   -----------     
  207.         QwriteLV    Yes   32.6   9.5    74.9   88.4   39.7   111.3  16.8     
  208.                     No    42.0   9.5    89.3  138.1   47.8   119.5  16.8     
  209.         QwriteV     Yes   32.8   9.5    75.4   88.4   40.0   112.1  16.7     
  210.                     No    42.4   9.5    90.0  138.1   48.6   119.5  16.8     
  211.         Qwrite      Yes   24.9   7.2    52.2   74.5   29.1    87.3  14.4     
  212.                     No    29.7   7.2    58.7  102.7   33.6    92.0  14.4     
  213.         QwriteC     Yes   24.6   7.2    51.9   74.0   29.0    86.8  14.3     
  214.                     No    29.6   7.2    58.1  102.7   33.0    90.9  14.4     
  215.         QwriteCV    Yes   32.6   9.5    74.9   89.0   39.5   111.0  16.8     
  216.                     No    41.6   9.5    89.3  138.1   47.8   119.0  16.8     
  217.         QfillC      Yes   81.2  11.9   166.6  147.3  122.5   244.3  21.5     
  218.                     No    72.6   7.4   141.3  174.4   90.5   176.9  14.0     
  219.         Qfill       Yes   81.2  11.8   164.1  147.3  122.5   246.1  21.5     
  220.                     No    73.7   7.4   141.3  174.4   90.5   177.9  14.0     
  221.         Qattr       Yes   72.6   7.4   141.3  174.4   90.5   177.9  14.0     
  222.         QattrC      Yes   72.6   7.4   141.3  174.4   90.5   177.9  14.0     
  223.         QstoreToMem n/a   59.1   7.2   111.6  127.4   78.4   181.9  13.8     
  224.         QstoreToScr n/a   59.1   7.0   111.6  126.2   78.4   183.9  13.7     
  225.  
  226.  
  227.         ADDRESSING IN THE MODULES:
  228.  
  229.         Turbo 3.0 compiles some code before and after procedures:
  230.  
  231.           1. 7 bytes before.
  232.           2. 7 bytes after without parameters.
  233.           3. 9 bytes after with parameters.
  234.  
  235.         To keep from changing the stack base pointer, these code bytes are 
  236.         bypassed.  They are addressed in the inline code as:
  237.  
  238.             call  >QwritesDisp-*+5
  239.  
  240.         instead of the usual "...*-2" which is the normal entry location 
  241.         for a procedure.  Future versions of Turbo may be different and 
  242.         the offset value may need to be changed as well as negative 
  243.         references to the base pointer such as "[BP-$04]".  I will try to 
  244.         keep up to date.
  245.  
  246.  
  247.         MODIFICATIONS:
  248.  
  249.         Base Coordinates - If you want to change the upper left corner to
  250.         be 0,0 instead of 1,1, you need to do the following on the inline
  251.         codes described with "Convert to 0-?? range":
  252.  
  253.            1. In QwriteLV, QwriteV, Qwrite, Qfill, and Qattr replace
  254.               DEC DI with NOP which has an inline code of $90.
  255.            2. In QwritesDisp and QfillsDisp, delete DEC DX and DEC AX.
  256.            3. In QwriteC, QwriteCV, QfillC, and QattrC change DEC DI to
  257.               INC DI which has a inline code of $40.
  258.            4. In QstoreToMem and QstoreToScr, replace DEC AX, DEC SI
  259.               and DEC DI with NOP.
  260.            5. In GotoRC, delete DEC DH and DEC DL.
  261.  
  262.  
  263.         APPLICATIONS:
  264.  
  265.         Multi-level Windows - An application of QWIK30.INC is multi-level 
  266.         windows.  The code has already been done in a file called 
  267.         WINDOW34.ARC.  It creates protected removable windows with 
  268.         Macintosh-like special special effects.
  269.  
  270.         Multi-level Pull-down Menus - An application of windows is multi-
  271.         level pull-down menus.  I have already created some very thorough 
  272.         code in a file called PULL15.ARC.  It is fully featured and fully 
  273.         configurable.  Includes execute, single, and multiple choice 
  274.         menus, unlimited nested submenus, data entry windows, help 
  275.         windows, directory windows, message system, and fully completed 
  276.         interfaces. 
  277.  
  278.         On-line source - All updated files can be found on the CompuServe 
  279.         Borland Forum (GO BORPRO) in the MSDOS Turbo Pascal Data Library.
  280.  
  281.  
  282.         CREDITS:
  283.  
  284.         Without the assistance and original ideas from Brian Foley
  285.         [76317,3247], these routines would not have been written.  In
  286.         addition, Dave Baldwin's InLine Assembler was essential in its
  287.         development.
  288.  
  289.         Copyright (c) 1986,1987 by Jim LeMay
  290.         Even though this is source code, it is still protected by the 
  291.         United States Copyright Law.
  292.  
  293.         If there are any problems, please let me know.
  294.         Jim LeMay [76011,217]  (1-817-735-4833  after 1800 CST)
  295.         6341 Klamath Rd., Ft. Worth, TX, 76116.
  296.  
  297.  
  298.         PRICE:
  299.  
  300.         These procedures are now ShareWare and the price may range from $5 
  301.         to $15 depending on your application.  See STATMENT.LIC in 
  302.         LICENSE.ARC for details.  
  303.  
  304.  
  305.         APPENDIX:
  306.  
  307.         Quick Reference List of all procedures and parameters:
  308.  
  309.           Qinit;
  310.  
  311.           QwriteLV (Row, Col: byte; Attr, Length: integer; VAR St);
  312.           QwriteV  (Row, Col: byte; Attr: integer; VAR St);
  313.           Qwrite   (Row, Col: byte; Attr: integer; St: Str80);
  314.           QwriteC  (Row, ColL, ColR: byte; Attr: integer; St: Str80);
  315.           QwriteCV (Row, ColL, ColR: byte; Attr: integer; VAR St);
  316.  
  317.           QfillC (Row, ColL, ColR, Rows, Cols: byte; Attr: integer; Ch: char);
  318.           Qfill  (Row, Col, Rows, Cols: byte; Attr: integer; Ch: char);
  319.           Qattr  (Row, Col, Rows, Cols: byte; Attr: integer);
  320.           QattrC (Row, ColL, ColR, Rows, Cols: byte; Attr: integer);
  321.  
  322.           QstoreToMem (Row, Col, Rows, Cols: byte; VAR Dest);
  323.           QstoreToScr (Row, Col, Rows, Cols: byte; VAR Source);
  324.  
  325.           QviewPage  (Page: byte);
  326.           QwritePage (Page: byte);
  327.  
  328.           GotoRC (Row, Col: Byte);
  329.           CursorChange (New: integer; VAR Old: integer);
  330.           CursorOff;
  331.           CursorOn;
  332.  
  333.  
  334.         REVISIONS:
  335.  
  336.         Version 1.1 (10-31-86):
  337.            Improved speed about 15%.
  338.            Corrected segment error for Mono mode.
  339.  
  340.         Version 1.2 (11-04-86):
  341.            Added self-centering routines.
  342.            Added document and complete demo.
  343.  
  344.         Version 1.3 (11-10-86):
  345.            Reduced assembly code 60% by using modules.
  346.            Added CursorChange procedure.
  347.            Improved speed on Qfill and Qattr about 5%.
  348.            Corrected Qfill bug.  (Extra characters were added when
  349.               attr<0 and Cols=even.)
  350.            Changed EGA detection to use Mono rather than CGA loops.
  351.            Added page capability to GotoRC.
  352.  
  353.         Version 2.0 (11-24-86):
  354.            Complete revision for global access to paging, retrace, and
  355.               segment address.  Permits formats in any column mode (40
  356.               80,120, or whatever).
  357.            Changed Qfill and Qattr for easier Row-by-Column blocks.
  358.            Added QfillC and QattrC for self-centering.
  359.            Added two page procedures.
  360.            Added two screen memory transfer procedures for Row-by-Column
  361.               blocks.
  362.            Increased speed of Qfill with attribute on CGA by 65%.
  363.  
  364.         Version 2.1 (12-09-86):
  365.            Added QwriteLV for partial string writing.
  366.            Added interrupt enable in QwritesDisp and QfillsDisp at
  367.               the end of writing in the vertical band for color.
  368.            Fixed bug in QstoreToScr to access other segments.
  369.            Modified Qdemo.pas for MDA and any column mode.
  370.            Added Qbench.pas to check speed on your own system.
  371.  
  372.         Version 3.0 (08-31-87):
  373.            Modified Qinit to handle the entire IBM PC family of computers.
  374.            Added the procedures CursorOff and CursorOn.
  375.            Added the document files QINIT.DOC and CURSOR.DOC.
  376.            Improved module addressing, eliminating any precautions of 
  377.               location.
  378.            Added QINITEST.PAS to check detection by QINIT.INC.
  379.            Modified QBENCH.PAS for new QINIT.INC.
  380.            Renamed QDEMO.PAS to QWIKDEMO.PAS.
  381.